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

src/Payment/PaymentRepository.php

@@ -272,6 +272,61 @@ class PaymentRepository {
 		);
 	}
 
+	/**
+	 * Whether a registration has an unscheduled, un-voided charge — one taken at
+	 * registration (`period_key IS NULL`, `status != failed`). The billing-mode
+	 * reconciler uses this to spot an up-front charge that a newly-scheduled
+	 * offering would otherwise cause the scan to bill a second time.
+	 */
+	public function hasUnscheduledCharge( string $registrationType, int $registrationId ): bool {
+		$found = $this->db->get_var(
+			$this->db->prepare(
+				'SELECT id FROM %i WHERE registration_type = %s AND registration_id = %d AND period_key IS NULL AND status != %s LIMIT 1',
+				$this->table,
+				$registrationType,
+				$registrationId,
+				Payment::STATUS_FAILED
+			)
+		);
+
+		return null !== $found;
+	}
+
+	/**
+	 * Stamp a registration's existing unscheduled charge with a billing period and
+	 * due date so the daily scan treats that period as already billed. Used when
+	 * an offering is switched to scheduled billing: the charge taken at enrolment
+	 * (which carries no `period_key`) would otherwise never match the scan's
+	 * per-period dedup, and the enrolment would be billed a second time for the
+	 * period the up-front charge already covers.
+	 *
+	 * Only ever adopts a charge that is genuinely unscheduled (`period_key IS
+	 * NULL`) and not voided (`status != failed`) — so it cannot overwrite a real
+	 * scheduled charge or revive a cancelled one. The caller guards against a
+	 * period that already has a scheduled charge (see {@see existsForPeriod}).
+	 * Returns the number of rows adopted (0 or 1).
+	 */
+	public function claimPeriodForUnscheduled( string $registrationType, int $registrationId, string $periodKey, string $dueDate ): int {
+		$sql = $this->db->prepare(
+			'UPDATE %i SET period_key = %s, due_date = %s
+			 WHERE registration_type = %s AND registration_id = %d
+			   AND period_key IS NULL AND status != %s
+			 ORDER BY id ASC LIMIT 1',
+			$this->table,
+			$periodKey,
+			$dueDate,
+			$registrationType,
+			$registrationId,
+			Payment::STATUS_FAILED
+		);
+
+		if ( null === $sql ) {
+			return 0;
+		}
+
+		return (int) $this->db->query( $sql );
+	}
+
 	/**
 	 * Atomically claim a payment for its one due-payment notice. Stamps
 	 * `notice_sent_at` only if it is still null, and returns whether *this* call