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

@@ -0,0 +1,135 @@
+# app/modules/loyalty/models/company_settings.py
+"""
+Company loyalty settings database model.
+
+Admin-controlled settings that apply to a company's loyalty program.
+These settings are managed by platform administrators, not vendors.
+"""
+
+from sqlalchemy import (
+    Boolean,
+    Column,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+)
+from sqlalchemy.orm import relationship
+
+from app.core.database import Base
+from models.database.base import TimestampMixin
+
+
+class StaffPinPolicy(str):
+    """Staff PIN policy options."""
+
+    REQUIRED = "required"  # Staff PIN always required
+    OPTIONAL = "optional"  # Vendor can choose
+    DISABLED = "disabled"  # Staff PIN not used
+
+
+class CompanyLoyaltySettings(Base, TimestampMixin):
+    """
+    Admin-controlled settings for company loyalty programs.
+
+    These settings are managed by platform administrators and
+    cannot be changed by vendors. They apply to all vendors
+    within the company.
+    """
+
+    __tablename__ = "company_loyalty_settings"
+
+    id = Column(Integer, primary_key=True, index=True)
+
+    # Company association (one settings per company)
+    company_id = Column(
+        Integer,
+        ForeignKey("companies.id", ondelete="CASCADE"),
+        unique=True,
+        nullable=False,
+        index=True,
+        comment="Company these settings apply to",
+    )
+
+    # =========================================================================
+    # Staff PIN Policy (Admin-controlled)
+    # =========================================================================
+    staff_pin_policy = Column(
+        String(20),
+        default=StaffPinPolicy.REQUIRED,
+        nullable=False,
+        comment="Staff PIN policy: required, optional, disabled",
+    )
+    staff_pin_lockout_attempts = Column(
+        Integer,
+        default=5,
+        nullable=False,
+        comment="Max failed PIN attempts before lockout",
+    )
+    staff_pin_lockout_minutes = Column(
+        Integer,
+        default=30,
+        nullable=False,
+        comment="Lockout duration in minutes",
+    )
+
+    # =========================================================================
+    # Feature Toggles (Admin-controlled)
+    # =========================================================================
+    allow_self_enrollment = Column(
+        Boolean,
+        default=True,
+        nullable=False,
+        comment="Allow customers to self-enroll via QR code",
+    )
+    allow_void_transactions = Column(
+        Boolean,
+        default=True,
+        nullable=False,
+        comment="Allow voiding points for returns",
+    )
+    allow_cross_location_redemption = Column(
+        Boolean,
+        default=True,
+        nullable=False,
+        comment="Allow redemption at any company location",
+    )
+
+    # =========================================================================
+    # Audit Settings
+    # =========================================================================
+    require_order_reference = Column(
+        Boolean,
+        default=False,
+        nullable=False,
+        comment="Require order reference when earning points",
+    )
+    log_ip_addresses = Column(
+        Boolean,
+        default=True,
+        nullable=False,
+        comment="Log IP addresses for transactions",
+    )
+
+    # =========================================================================
+    # Relationships
+    # =========================================================================
+    company = relationship("Company", backref="loyalty_settings")
+
+    # Indexes
+    __table_args__ = (
+        Index("idx_company_loyalty_settings_company", "company_id"),
+    )
+
+    def __repr__(self) -> str:
+        return f"<CompanyLoyaltySettings(id={self.id}, company_id={self.company_id}, pin_policy='{self.staff_pin_policy}')>"
+
+    @property
+    def is_staff_pin_required(self) -> bool:
+        """Check if staff PIN is required."""
+        return self.staff_pin_policy == StaffPinPolicy.REQUIRED
+
+    @property
+    def is_staff_pin_disabled(self) -> bool:
+        """Check if staff PIN is disabled."""
+        return self.staff_pin_policy == StaffPinPolicy.DISABLED