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/schemas/stamp.py

@@ -0,0 +1,114 @@
+# app/modules/loyalty/schemas/stamp.py
+"""
+Pydantic schemas for stamp operations.
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class StampRequest(BaseModel):
+    """Schema for adding a stamp to a card."""
+
+    card_id: int | None = Field(
+        None,
+        description="Card ID (use this or qr_code)",
+    )
+    qr_code: str | None = Field(
+        None,
+        description="QR code data from card scan",
+    )
+    card_number: str | None = Field(
+        None,
+        description="Card number (manual entry)",
+    )
+
+    # Authentication
+    staff_pin: str | None = Field(
+        None,
+        min_length=4,
+        max_length=6,
+        description="Staff PIN for verification",
+    )
+
+    # Optional metadata
+    notes: str | None = Field(
+        None,
+        max_length=500,
+        description="Optional note about this stamp",
+    )
+
+
+class StampResponse(BaseModel):
+    """Schema for stamp operation response."""
+
+    success: bool = True
+    message: str = "Stamp added successfully"
+
+    # Card state after stamp
+    card_id: int
+    card_number: str
+    stamp_count: int
+    stamps_target: int
+    stamps_until_reward: int
+
+    # Did this trigger a reward?
+    reward_earned: bool = False
+    reward_description: str | None = None
+
+    # Cooldown info
+    next_stamp_available_at: datetime | None = None
+
+    # Today's activity
+    stamps_today: int
+    stamps_remaining_today: int
+
+
+class StampRedeemRequest(BaseModel):
+    """Schema for redeeming stamps for a reward."""
+
+    card_id: int | None = Field(
+        None,
+        description="Card ID (use this or qr_code)",
+    )
+    qr_code: str | None = Field(
+        None,
+        description="QR code data from card scan",
+    )
+    card_number: str | None = Field(
+        None,
+        description="Card number (manual entry)",
+    )
+
+    # Authentication
+    staff_pin: str | None = Field(
+        None,
+        min_length=4,
+        max_length=6,
+        description="Staff PIN for verification",
+    )
+
+    # Optional metadata
+    notes: str | None = Field(
+        None,
+        max_length=500,
+        description="Optional note about this redemption",
+    )
+
+
+class StampRedeemResponse(BaseModel):
+    """Schema for stamp redemption response."""
+
+    success: bool = True
+    message: str = "Reward redeemed successfully"
+
+    # Card state after redemption
+    card_id: int
+    card_number: str
+    stamp_count: int  # Should be 0 after redemption
+    stamps_target: int
+
+    # Reward info
+    reward_description: str
+    total_redemptions: int  # Lifetime redemptions for this card