Reconcile up-front charges when a class switches to monthly billing

A student who enrols while a group class is pay-now is charged once at
enrolment, and that charge carries no period_key. When the class is
later switched to monthly, the daily scan — which dedups scheduled
charges by period_key — does not see the up-front charge and bills the
enrolment again for the current month, double-charging students who
had already paid. The differing payer between the two rows (student vs
guardian) was a side effect of guardian links created between the two
charge dates, not the cause.

Switching a group class into monthly now adopts each active enrolment's
up-front charge into the current month (stamping period_key and
due_date) so the scan treats that month as billed and charges from the
next month on. Enrolments with no up-front charge, or already billed
for the month, are left alone; weekly and non-group offerings are not
touched. Wired into both offering-update paths (admin form and REST).

Co-authored-by: anthropic/claude-opus-4-8

tests/Unit/Payment/PaymentRepositoryTest.php

@@ -179,6 +179,52 @@ class PaymentRepositoryTest extends TestCase
         self::assertFalse($this->repo->backfillNoticeSent());
     }
 
+    public function testHasUnscheduledChargeTrueWhenUpfrontChargeExists(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::pattern('/period_key IS NULL AND status != %s/'), 'wp_us_payments', Payment::REG_ENROLLMENT, 7, Payment::STATUS_FAILED)
+            ->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_var')->once()->with('SELECT ...')->andReturn('3');
+
+        self::assertTrue($this->repo->hasUnscheduledCharge(Payment::REG_ENROLLMENT, 7));
+    }
+
+    public function testHasUnscheduledChargeFalseWhenNoneOrOnlyVoided(): void
+    {
+        $this->db->shouldReceive('prepare')->once()->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_var')->once()->andReturn(null);
+
+        self::assertFalse($this->repo->hasUnscheduledCharge(Payment::REG_ENROLLMENT, 7));
+    }
+
+    public function testClaimPeriodForUnscheduledStampsPeriodAndDueDate(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(
+                Mockery::pattern('/SET period_key = %s, due_date = %s.*period_key IS NULL AND status != %s/s'),
+                'wp_us_payments',
+                '2026-09',
+                '2026-09-01',
+                Payment::REG_ENROLLMENT,
+                7,
+                Payment::STATUS_FAILED
+            )
+            ->andReturn('UPDATE ...');
+        $this->db->shouldReceive('query')->once()->with('UPDATE ...')->andReturn(1);
+
+        self::assertSame(1, $this->repo->claimPeriodForUnscheduled(Payment::REG_ENROLLMENT, 7, '2026-09', '2026-09-01'));
+    }
+
+    public function testClaimPeriodForUnscheduledAdoptsNothingWhenNoMatch(): void
+    {
+        $this->db->shouldReceive('prepare')->once()->andReturn('UPDATE ...');
+        $this->db->shouldReceive('query')->once()->with('UPDATE ...')->andReturn(0);
+
+        self::assertSame(0, $this->repo->claimPeriodForUnscheduled(Payment::REG_ENROLLMENT, 7, '2026-09', '2026-09-01'));
+    }
+
     public function testUpdateTaxRecomputesAmountFromRate(): void
     {
         $this->db->shouldReceive('prepare')