chore: add inline documentation

src/Entity/TravelSnapshot.php

@@ -13,6 +13,18 @@ use Doctrine\ORM\Mapping as ORM;
 #[ORM\Index(name: 'idx_snapshot_product_id', columns: ['product_id'])]
 #[ORM\Index(name: 'idx_snapshot_date_to', columns: ['date_to'])]
 #[ORM\Index(name: 'idx_snapshot_extended_refreshed_at', columns: ['extended_refreshed_at'])]
+/**
+ * Persisted copy of a Travel aggregate for travels whose source XML may no longer be available.
+ *
+ * Each row stores the full serialized Travel graph as a JSON payload alongside a set of
+ * denormalized metadata columns (code, label, dates, hotel) that allow filtering and
+ * mapping lookups without deserializing the payload.
+ *
+ * Three timestamps track the lifecycle of the snapshot:
+ *   - capturedAt:          when the snapshot was first written
+ *   - updatedAt:           when the payload or metadata was last modified
+ *   - extendedRefreshedAt: when extended availability (VERFUEGBARKEIT2) was last applied
+ */
 class TravelSnapshot
 {
     #[ORM\Id]
@@ -50,9 +62,11 @@ class TravelSnapshot
     #[ORM\Column(type: 'date_immutable', nullable: true)]
     private ?\DateTimeImmutable $dateTo = null;
 
+    /** Full JSON-serialized Travel aggregate. */
     #[ORM\Column(type: 'text')]
     private string $payload;
 
+    /** SHA-256 of payload; compared before every write to skip no-op flushes. */
     #[ORM\Column(type: 'string', length: 64)]
     private string $payloadHash;