feat(loyalty): implement Phase 2 - company-wide points system

Complete implementation of loyalty module Phase 2 features:

Database & Models:
- Add company_id to LoyaltyProgram for chain-wide loyalty
- Add company_id to LoyaltyCard for multi-location support
- Add CompanyLoyaltySettings model for admin-controlled settings
- Add points expiration, welcome bonus, and minimum redemption fields
- Add POINTS_EXPIRED, WELCOME_BONUS transaction types

Services:
- Update program_service for company-based queries
- Update card_service with enrollment and welcome bonus
- Update points_service with void_points for returns
- Update stamp_service for company context
- Update pin_service for company-wide operations

API Endpoints:
- Admin: Program listing with stats, company detail views
- Vendor: Terminal operations, card management, settings
- Storefront: Customer card/transactions, self-enrollment

UI Templates:
- Admin: Programs dashboard, company detail, settings
- Vendor: Terminal, cards list, card detail, settings, stats, enrollment
- Storefront: Dashboard, history, enrollment, success pages

Background Tasks:
- Point expiration task (daily, based on inactivity)
- Wallet sync task (hourly)

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

app/modules/loyalty/models/loyalty_transaction.py

@@ -2,9 +2,15 @@
 """
 Loyalty transaction database model.
 
+Company-based transaction tracking:
+- Tracks which company and vendor processed each transaction
+- Enables chain-wide reporting while maintaining per-location audit trails
+- Supports voiding transactions for returns
+
 Records all loyalty events including:
 - Stamps earned and redeemed
 - Points earned and redeemed
+- Welcome bonuses and expirations
 - Associated metadata (staff PIN, purchase amount, IP, etc.)
 """
 
@@ -31,10 +37,12 @@ class TransactionType(str, enum.Enum):
     # Stamps
     STAMP_EARNED = "stamp_earned"
     STAMP_REDEEMED = "stamp_redeemed"
+    STAMP_VOIDED = "stamp_voided"  # Stamps voided due to return
 
     # Points
     POINTS_EARNED = "points_earned"
     POINTS_REDEEMED = "points_redeemed"
+    POINTS_VOIDED = "points_voided"  # Points voided due to return
 
     # Adjustments (manual corrections by staff)
     STAMP_ADJUSTMENT = "stamp_adjustment"
@@ -44,6 +52,10 @@ class TransactionType(str, enum.Enum):
     CARD_CREATED = "card_created"
     CARD_DEACTIVATED = "card_deactivated"
 
+    # Bonuses and expiration
+    WELCOME_BONUS = "welcome_bonus"  # Welcome bonus points on enrollment
+    POINTS_EXPIRED = "points_expired"  # Points expired due to inactivity
+
 
 class LoyaltyTransaction(Base, TimestampMixin):
     """
@@ -51,12 +63,25 @@ class LoyaltyTransaction(Base, TimestampMixin):
 
     Immutable audit log of all loyalty operations for fraud
     detection, analytics, and customer support.
+
+    Tracks which vendor (location) processed the transaction,
+    enabling chain-wide reporting while maintaining per-location
+    audit trails.
     """
 
     __tablename__ = "loyalty_transactions"
 
     id = Column(Integer, primary_key=True, index=True)
 
+    # Company association
+    company_id = Column(
+        Integer,
+        ForeignKey("companies.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+        comment="Company that owns the loyalty program",
+    )
+
     # Core relationships
     card_id = Column(
         Integer,
@@ -66,10 +91,10 @@ class LoyaltyTransaction(Base, TimestampMixin):
     )
     vendor_id = Column(
         Integer,
-        ForeignKey("vendors.id", ondelete="CASCADE"),
-        nullable=False,
+        ForeignKey("vendors.id", ondelete="SET NULL"),
+        nullable=True,
         index=True,
-        comment="Denormalized for query performance",
+        comment="Vendor (location) that processed this transaction",
     )
     staff_pin_id = Column(
         Integer,
@@ -79,6 +104,15 @@ class LoyaltyTransaction(Base, TimestampMixin):
         comment="Staff PIN used for this operation",
     )
 
+    # Related transaction (for voids/returns)
+    related_transaction_id = Column(
+        Integer,
+        ForeignKey("loyalty_transactions.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+        comment="Original transaction (for voids/returns)",
+    )
+
     # =========================================================================
     # Transaction Details
     # =========================================================================
@@ -175,15 +209,23 @@ class LoyaltyTransaction(Base, TimestampMixin):
     # =========================================================================
     # Relationships
     # =========================================================================
+    company = relationship("Company", backref="loyalty_transactions")
     card = relationship("LoyaltyCard", back_populates="transactions")
     vendor = relationship("Vendor", backref="loyalty_transactions")
     staff_pin = relationship("StaffPin", backref="transactions")
+    related_transaction = relationship(
+        "LoyaltyTransaction",
+        remote_side=[id],
+        backref="voiding_transactions",
+    )
 
     # Indexes
     __table_args__ = (
         Index("idx_loyalty_tx_card_type", "card_id", "transaction_type"),
         Index("idx_loyalty_tx_vendor_date", "vendor_id", "transaction_at"),
         Index("idx_loyalty_tx_type_date", "transaction_type", "transaction_at"),
+        Index("idx_loyalty_tx_company_date", "company_id", "transaction_at"),
+        Index("idx_loyalty_tx_company_vendor", "company_id", "vendor_id"),
     )
 
     def __repr__(self) -> str:
@@ -202,6 +244,7 @@ class LoyaltyTransaction(Base, TimestampMixin):
         return self.transaction_type in (
             TransactionType.STAMP_EARNED.value,
             TransactionType.STAMP_REDEEMED.value,
+            TransactionType.STAMP_VOIDED.value,
             TransactionType.STAMP_ADJUSTMENT.value,
         )
 
@@ -212,6 +255,9 @@ class LoyaltyTransaction(Base, TimestampMixin):
             TransactionType.POINTS_EARNED.value,
             TransactionType.POINTS_REDEEMED.value,
             TransactionType.POINTS_ADJUSTMENT.value,
+            TransactionType.POINTS_VOIDED.value,
+            TransactionType.WELCOME_BONUS.value,
+            TransactionType.POINTS_EXPIRED.value,
         )
 
     @property
@@ -220,6 +266,7 @@ class LoyaltyTransaction(Base, TimestampMixin):
         return self.transaction_type in (
             TransactionType.STAMP_EARNED.value,
             TransactionType.POINTS_EARNED.value,
+            TransactionType.WELCOME_BONUS.value,
         )
 
     @property
@@ -230,9 +277,24 @@ class LoyaltyTransaction(Base, TimestampMixin):
             TransactionType.POINTS_REDEEMED.value,
         )
 
+    @property
+    def is_void_transaction(self) -> bool:
+        """Check if this is a void transaction (for returns)."""
+        return self.transaction_type in (
+            TransactionType.POINTS_VOIDED.value,
+            TransactionType.STAMP_VOIDED.value,
+        )
+
     @property
     def staff_name(self) -> str | None:
         """Get the name of the staff member who performed this transaction."""
         if self.staff_pin:
             return self.staff_pin.name
         return None
+
+    @property
+    def vendor_name(self) -> str | None:
+        """Get the name of the vendor where this transaction occurred."""
+        if self.vendor:
+            return self.vendor.name
+        return None