feat(loyalty): implement complete loyalty module MVP

Add stamp-based and points-based loyalty programs for vendors with:

Database Models (5 tables):
- loyalty_programs: Vendor program configuration
- loyalty_cards: Customer cards with stamp/point balances
- loyalty_transactions: Immutable audit log
- staff_pins: Fraud prevention PINs (bcrypt hashed)
- apple_device_registrations: Apple Wallet push tokens

Services:
- program_service: Program CRUD and statistics
- card_service: Customer enrollment and card lookup
- stamp_service: Stamp operations with anti-fraud checks
- points_service: Points earning and redemption
- pin_service: Staff PIN management with lockout
- wallet_service: Unified wallet abstraction
- google_wallet_service: Google Wallet API integration
- apple_wallet_service: Apple Wallet .pkpass generation

API Routes:
- Admin: /api/v1/admin/loyalty/* (programs list, stats)
- Vendor: /api/v1/vendor/loyalty/* (stamp, points, cards, PINs)
- Public: /api/v1/loyalty/* (enrollment, Apple Web Service)

Anti-Fraud Features:
- Staff PIN verification (configurable per program)
- Cooldown period between stamps (default 15 min)
- Daily stamp limits (default 5/day)
- PIN lockout after failed attempts

Wallet Integration:
- Google Wallet: LoyaltyClass and LoyaltyObject management
- Apple Wallet: .pkpass generation with PKCS#7 signing
- Apple Web Service endpoints for device registration/updates

Also includes:
- Alembic migration for all tables with indexes
- Localization files (en, fr, de, lu)
- Module documentation
- Phase 2 interface and user journey plan

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

app/modules/loyalty/definition.py

@@ -0,0 +1,118 @@
+# app/modules/loyalty/definition.py
+"""
+Loyalty module definition.
+
+Defines the loyalty module including its features, menu items,
+route configurations, and scheduled tasks.
+"""
+
+from app.modules.base import ModuleDefinition, ScheduledTask
+from models.database.admin_menu_config import FrontendType
+
+
+def _get_admin_router():
+    """Lazy import of admin router to avoid circular imports."""
+    from app.modules.loyalty.routes.api.admin import admin_router
+
+    return admin_router
+
+
+def _get_vendor_router():
+    """Lazy import of vendor router to avoid circular imports."""
+    from app.modules.loyalty.routes.api.vendor import vendor_router
+
+    return vendor_router
+
+
+def _get_public_router():
+    """Lazy import of public router to avoid circular imports."""
+    from app.modules.loyalty.routes.api.public import public_router
+
+    return public_router
+
+
+# Loyalty module definition
+loyalty_module = ModuleDefinition(
+    code="loyalty",
+    name="Loyalty Programs",
+    description=(
+        "Stamp-based and points-based loyalty programs with Google Wallet "
+        "and Apple Wallet integration. Includes anti-fraud features like "
+        "staff PINs, cooldown periods, and daily limits."
+    ),
+    version="1.0.0",
+    requires=["customers"],  # Depends on customers module for customer data
+    features=[
+        # Core features
+        "loyalty_stamps",  # Stamp-based loyalty
+        "loyalty_points",  # Points-based loyalty
+        "loyalty_hybrid",  # Both stamps and points
+        # Card management
+        "loyalty_cards",  # Customer card management
+        "loyalty_enrollment",  # Customer enrollment
+        # Staff/fraud prevention
+        "loyalty_staff_pins",  # Staff PIN management
+        "loyalty_anti_fraud",  # Cooldown, daily limits
+        # Wallet integration
+        "loyalty_google_wallet",  # Google Wallet passes
+        "loyalty_apple_wallet",  # Apple Wallet passes
+        # Analytics
+        "loyalty_stats",  # Dashboard statistics
+        "loyalty_reports",  # Transaction reports
+    ],
+    menu_items={
+        FrontendType.ADMIN: [
+            "loyalty-programs",  # View all programs
+            "loyalty-analytics",  # Platform-wide stats
+        ],
+        FrontendType.VENDOR: [
+            "loyalty",  # Loyalty dashboard
+            "loyalty-cards",  # Customer cards
+            "loyalty-stats",  # Vendor stats
+        ],
+    },
+    is_core=False,  # Loyalty can be disabled
+    # =========================================================================
+    # Self-Contained Module Configuration
+    # =========================================================================
+    is_self_contained=True,
+    services_path="app.modules.loyalty.services",
+    models_path="app.modules.loyalty.models",
+    schemas_path="app.modules.loyalty.schemas",
+    exceptions_path="app.modules.loyalty.exceptions",
+    tasks_path="app.modules.loyalty.tasks",
+    # =========================================================================
+    # Scheduled Tasks
+    # =========================================================================
+    scheduled_tasks=[
+        ScheduledTask(
+            name="loyalty.sync_wallet_passes",
+            task="app.modules.loyalty.tasks.wallet_sync.sync_wallet_passes",
+            schedule="0 * * * *",  # Hourly
+            options={"queue": "scheduled"},
+        ),
+        ScheduledTask(
+            name="loyalty.expire_points",
+            task="app.modules.loyalty.tasks.point_expiration.expire_points",
+            schedule="0 2 * * *",  # Daily at 02:00
+            options={"queue": "scheduled"},
+        ),
+    ],
+)
+
+
+def get_loyalty_module_with_routers() -> ModuleDefinition:
+    """
+    Get loyalty module with routers attached.
+
+    This function attaches the routers lazily to avoid circular imports
+    during module initialization.
+    """
+    loyalty_module.admin_router = _get_admin_router()
+    loyalty_module.vendor_router = _get_vendor_router()
+    # Note: public_router needs to be attached separately in main.py
+    # as it doesn't require authentication
+    return loyalty_module
+
+
+__all__ = ["loyalty_module", "get_loyalty_module_with_routers"]