feat(arch): implement soft delete for business-critical models

Adds SoftDeleteMixin (deleted_at + deleted_by_id) with automatic query
filtering via do_orm_execute event. Soft-deleted records are invisible
by default; bypass with execution_options={"include_deleted": True}.

Models: User, Merchant, Store, StoreUser, Customer, Order, Product,
LoyaltyProgram, LoyaltyCard.

Infrastructure:
- SoftDeleteMixin in models/database/base.py
- Auto query filter registered on SessionLocal and test sessions
- soft_delete(), restore(), soft_delete_cascade() in app/core/soft_delete.py
- Alembic migration adding columns to 9 tables
- Partial unique indexes on users.email/username, stores.store_code/subdomain

Service changes:
- admin_service: delete_user, delete_store → soft_delete/soft_delete_cascade
- merchant_service: delete_merchant → soft_delete_cascade (stores→children)
- store_team_service: remove_team_member → soft_delete (fixes is_active bug)
- product_service: delete_product → soft_delete
- program_service: delete_program → soft_delete_cascade

Admin API:
- include_deleted/only_deleted query params on admin list endpoints
- PUT restore endpoints for users, merchants, stores

Tests: 9 unit tests for soft-delete infrastructure.
Docs: docs/backend/soft-delete.md + follow-up proposals.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

app/core/soft_delete.py

@@ -0,0 +1,143 @@
+# app/core/soft_delete.py
+"""
+Soft-delete utility functions.
+
+Provides helpers for soft-deleting, restoring, and cascade soft-deleting
+records that use the SoftDeleteMixin.
+
+Usage:
+    from app.core.soft_delete import soft_delete, restore, soft_delete_cascade
+
+    # Simple soft delete
+    soft_delete(db, user, deleted_by_id=admin.id)
+
+    # Cascade soft delete (merchant + all stores + their children)
+    soft_delete_cascade(db, merchant, deleted_by_id=admin.id, cascade_rels=[
+        ("stores", [("products", []), ("customers", []), ("orders", []), ("store_users", [])]),
+    ])
+
+    # Restore a soft-deleted record
+    from app.modules.tenancy.models import User
+    restore(db, User, entity_id=42, restored_by_id=admin.id)
+"""
+
+import logging
+from datetime import UTC, datetime
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+logger = logging.getLogger(__name__)
+
+
+def soft_delete(db: Session, entity, deleted_by_id: int | None = None) -> None:
+    """
+    Mark an entity as soft-deleted.
+
+    Sets deleted_at to now and deleted_by_id to the actor.
+    Does NOT call db.commit() — caller is responsible.
+
+    Args:
+        db: Database session.
+        entity: SQLAlchemy model instance with SoftDeleteMixin.
+        deleted_by_id: ID of the user performing the deletion.
+    """
+    entity.deleted_at = datetime.now(UTC)
+    entity.deleted_by_id = deleted_by_id
+    db.flush()
+
+    logger.info(
+        f"Soft-deleted {entity.__class__.__name__} id={entity.id} "
+        f"by user_id={deleted_by_id}"
+    )
+
+
+def restore(
+    db: Session,
+    model_class,
+    entity_id: int,
+    restored_by_id: int | None = None,
+):
+    """
+    Restore a soft-deleted entity.
+
+    Queries with include_deleted=True to find the record, then clears
+    deleted_at and deleted_by_id.
+
+    Args:
+        db: Database session.
+        model_class: SQLAlchemy model class.
+        entity_id: ID of the entity to restore.
+        restored_by_id: ID of the user performing the restore (for logging).
+
+    Returns:
+        The restored entity.
+
+    Raises:
+        ValueError: If entity not found.
+    """
+    entity = db.execute(
+        select(model_class).filter(model_class.id == entity_id),
+        execution_options={"include_deleted": True},
+    ).scalar_one_or_none()
+
+    if entity is None:
+        raise ValueError(f"{model_class.__name__} with id={entity_id} not found")
+
+    if entity.deleted_at is None:
+        raise ValueError(f"{model_class.__name__} with id={entity_id} is not deleted")
+
+    entity.deleted_at = None
+    entity.deleted_by_id = None
+    db.flush()
+
+    logger.info(
+        f"Restored {model_class.__name__} id={entity_id} "
+        f"by user_id={restored_by_id}"
+    )
+    return entity
+
+
+def soft_delete_cascade(
+    db: Session,
+    entity,
+    deleted_by_id: int | None = None,
+    cascade_rels: list[tuple[str, list]] | None = None,
+) -> int:
+    """
+    Soft-delete an entity and recursively soft-delete its children.
+
+    Args:
+        db: Database session.
+        entity: SQLAlchemy model instance with SoftDeleteMixin.
+        deleted_by_id: ID of the user performing the deletion.
+        cascade_rels: List of (relationship_name, child_cascade_rels) tuples.
+            Example: [("stores", [("products", []), ("customers", [])])]
+
+    Returns:
+        Total number of records soft-deleted (including the root entity).
+    """
+    count = 0
+
+    # Soft-delete the entity itself
+    soft_delete(db, entity, deleted_by_id)
+    count += 1
+
+    # Recursively soft-delete children
+    if cascade_rels:
+        for rel_name, child_cascade in cascade_rels:
+            children = getattr(entity, rel_name, None)
+            if children is None:
+                continue
+
+            # Handle both collections and single items (uselist=False)
+            if not isinstance(children, list):
+                children = [children]
+
+            for child in children:
+                if hasattr(child, "deleted_at") and child.deleted_at is None:
+                    count += soft_delete_cascade(
+                        db, child, deleted_by_id, child_cascade
+                    )
+
+    return count