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/database.py

@@ -12,8 +12,8 @@ Note: This project uses PostgreSQL only. SQLite is not supported.
 
 import logging
 
-from sqlalchemy import create_engine
-from sqlalchemy.orm import declarative_base, sessionmaker
+from sqlalchemy import create_engine, event
+from sqlalchemy.orm import declarative_base, sessionmaker, with_loader_criteria
 from sqlalchemy.pool import QueuePool
 
 from .config import settings, validate_database_url
@@ -38,6 +38,45 @@ Base = declarative_base()
 logger = logging.getLogger(__name__)
 
 
+# ---------------------------------------------------------------------------
+# Soft-delete automatic query filter
+# ---------------------------------------------------------------------------
+# Any model that inherits SoftDeleteMixin will automatically have
+# `WHERE deleted_at IS NULL` appended to SELECT queries.
+# Bypass with: db.execute(stmt, execution_options={"include_deleted": True})
+# or db.query(Model).execution_options(include_deleted=True).all()
+# ---------------------------------------------------------------------------
+
+def register_soft_delete_filter(session_factory):
+    """Register the soft-delete query filter on a session factory.
+
+    Call this for any sessionmaker that should auto-exclude soft-deleted records.
+    Used for both the production SessionLocal and test session factories.
+    """
+
+    @event.listens_for(session_factory, "do_orm_execute")
+    def _soft_delete_filter(orm_execute_state):
+        if (
+            orm_execute_state.is_select
+            and not orm_execute_state.execution_options.get("include_deleted", False)
+        ):
+            from models.database.base import SoftDeleteMixin
+
+            orm_execute_state.statement = orm_execute_state.statement.options(
+                with_loader_criteria(
+                    SoftDeleteMixin,
+                    lambda cls: cls.deleted_at.is_(None),
+                    include_aliases=True,
+                )
+            )
+
+    return _soft_delete_filter
+
+
+# Register on the production session factory
+register_soft_delete_filter(SessionLocal)
+
+
 def get_db():
     """
     Database session dependency for FastAPI routes.