feat(package): session packages backed by a credit ledger

"Six laser sessions" is the common case in an aesthetics clinic: the patient
pays once and books the sessions later.

Credit is a ledger, not a counter. No table has a remaining/used_count column
and a schema test enforces that — the balance is always SUM(delta) over
append-only rows, so every number a patient sees has a full history behind it.
Corrections are new rows, never edits.

- purchase / consume / refund / adjustment / expiry, each with a reason, an
  author and the appointment it belongs to
- consume happens in confirm(), never in quote(): if the preview consumed, a
  page refresh would cost the patient a session
- cancelling adds a refund row; the consume row stays
- FIFO across a patient's packages — the oldest is closest to expiring
- an empty package is not an error, it just does not apply and the patient pays
- adjust/expire need a doctor or clinic role, and adjust always needs a reason
- app:package:expire writes the closing row so "where did my 3 sessions go?"
  always has an answer

Consume takes a pessimistic lock on the one package row. That is the opposite
of task 07's slot buckets, and docs/api/package.md carries the table explaining
why, so nobody unifies them later.

Idempotency checks for an existing consume row before inserting rather than
catching the unique violation: in Doctrine that exception closes the
EntityManager and burns the rest of the request. The unique key stays as the
last line of defence.

Admin: PackagesPage, a packages tab on the patient record, and a ledger page
whose running-balance column shows where the final number came from.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/Pricing/Service/PricingEngine.php

@@ -6,6 +6,8 @@ use App\ClinicService\Entity\ServiceItem;
 use App\ClinicService\Repository\ServiceBranchOverrideRepository;
 use App\ClinicService\Repository\TariffRepository;
 use App\Doctor\Entity\DoctorAddress;
+use App\Package\Service\PackageConsumptionService;
+use App\Patient\Entity\PatientRecord;
 use App\Pricing\Repository\PriceListItemRepository;
 use App\Pricing\Repository\PriceListRepository;
 use App\Pricing\ValueObject\PriceQuote;
@@ -37,6 +39,7 @@ final class PricingEngine
 {
     public function __construct(
         private readonly PolicyResolver                  $policies,
+        private readonly PackageConsumptionService       $packages,
         private readonly PriceListRepository             $priceLists,
         private readonly PriceListItemRepository         $priceListItems,
         private readonly ServiceBranchOverrideRepository $overrides,
@@ -59,6 +62,7 @@ final class PricingEngine
         DoctorAddress $address,
         int $at,
         array $policy = [],
+        ?PatientRecord $patient = null,
     ): PriceQuote {
         $entityType = $address->tenantEntityType();
         $entityId   = $address->tenantEntityId();
@@ -76,6 +80,17 @@ final class PricingEngine
 
         $subtotal = $base + $itemsTotal;
 
+        // ── پکیج ──────────────────────────────────────────────────────────────
+        // پکیج **قیمت پایهٔ سرویس** را می‌پوشاند، نه آیتم‌های اضافه: «شش جلسه لیزر»
+        // یعنی شش بار خودِ لیزر، نه هر چیزی که کنارش انتخاب شود.
+        $usable = $patient === null ? null : $this->packages->firstUsable($patient, $service, $at);
+        $covered = 0;
+
+        if ($usable !== null) {
+            $covered  = min($base, $subtotal);
+            $subtotal -= $covered;
+        }
+
         // ── تخفیف ─────────────────────────────────────────────────────────────
         // قوانین دستهٔ «قیمت» کنار سیاست دستیِ درخواست می‌نشینند، نه به‌جایش: تخفیفی
         // که اپراتور دستی می‌دهد و تخفیفی که قانون می‌دهد هر دو واقعی‌اند.
@@ -110,6 +125,14 @@ final class PricingEngine
 
         $deposit = max(0, min($deposit, $final));
 
+        if ($covered > 0) {
+            $discounts[] = [
+                'label' => sprintf('پوشش پکیج «%s»', $usable?->getPackage()->getName() ?? '—'),
+                'rials' => $covered,
+                'kind'  => 'package',
+            ];
+        }
+
         return new PriceQuote(
             baseRials: $base,
             itemsRials: $itemsTotal,
@@ -121,6 +144,8 @@ final class PricingEngine
             depositRials: $deposit,
             discounts: $discounts,
             sources: $sources,
+            packageWillBeConsumed: $usable !== null,
+            packageUuid: $usable?->getUuid(),
         );
     }